Fetch Company Details Advanced API
This document outlines the details of the Fetch Company Details Advanced API.
API Description
Objective
The Fetch Company Details Advanced API retrieves comprehensive company information by providing either the Corporate Identification Number (CIN), the Permanent Account Number (PAN), or both as inputs.
The Fetch Company Details Advanced API provides comprehensive company data from the Ministry of Corporate Affairs (MCA), including company profiles, director information, and financial details, making it ideal for corporate verification and due diligence.
| Input | Output |
|---|---|
| CIN or PAN or both | Details about:
|
API URL
The URL for the Fetch Company Details Advanced API is:
https://ind-engine.thomas.hyperverge.co/v1/fetchCompanyDetailsAdvanced
API Endpoint
The endpoint for the Fetch Company Details Advanced API is:
fetchCompanyDetailsAdvanced
Overview
The Fetch Company Details Advanced API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.
Authentication
You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the Fetch Company Details Advanced API.
API Request Details
Method - POST
Headers
| Header | Mandatory / Optional | Description | Input Format |
|---|---|---|---|
content-type | Mandatory | This parameter defines the media type for the request payload. | application/json |
appId | Mandatory | The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab. | Not Applicable - this is a unique value |
appKey | Mandatory | The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab. | Not Applicable - this is a unique value |
transactionId | Mandatory | A unique identifier for tracking a user journey | Not Applicable - this should be both unique and easily associated with the user's journey in your application(s) |
Input
The following table provides the details of the parameters required for the Fetch Company Details Advanced API's request body:
| Parameter | Mandatory / Optional | Type | Description | Input Format | Default Value |
|---|---|---|---|---|---|
cin | Selectively Optional | string | The 21-character Corporate Identification Number. At least one of CIN or PAN must be provided. | Valid 21-character CIN | Not Applicable |
pan | Selectively Optional | string | The 10-character company PAN number. At least one of CIN or PAN must be provided. | Valid 10-character company PAN | Not Applicable |
Request
The following code snippet demonstrates a standard curl request for the Fetch Company Details Advanced API:
curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchCompanyDetailsAdvanced' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
"cin": "<Enter_the_valid_CIN>",
"pan": "<Enter_the_valid_PAN>"
}'
Success Response
The following code snippet demonstrates a success response from the Fetch Company Details Advanced API:
{
"status": "success",
"statusCode": 200,
"result": {
"CompanyMasterSummary": {
"LastUpdatedDateTime": "24-09-2024",
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyRocCity": "<roc_city>",
"CompanyRegNumber": "<registration_number>",
"CompanyCategory": "<company_category>",
"CompanySubCategory": "<company_subcategory>",
"CompanyClass": "<company_class>",
"CompanyAuthCapital": "<authorised_capital>",
"CompanyPaidUpCapital": "<paid_up_capital>",
"CompanyFullAddress": "<full_address>",
"CompanyRegState": "<state>",
"CompanyRegCity": "<city>",
"CompanyRegPinCode": "<pincode>",
"CompanyBookAddress": "null",
"CompanyMcaStatus": "<mca_status>",
"CompanyLastAgmDate": "<last_agm_date>",
"CompanyLastBsDate": "<last_bs_date>",
"CompanyEmail": "<email>",
"CompanyWebSite": "<website>",
"CompanyMcaIndustry": "<industry>",
"CompanyMcaIndustryDivision": "<industry_division>",
"CompanyMcaIndustryGroup": "<industry_group>",
"StatusUnderCIRP": "null"
},
"DirectorSignatoryMasterBasic": {
"LastUpdatedDateTime": "<DD-MM-YYYY>",
"DirectorCurrentMasterBasic": {
"Director": [
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
}
]
},
"DirectorPastMasterBasic": {
"Director": [
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": "<designation>",
"DirectorDateOfAppnt": "<appointment_date>",
"Directorship": null
}
]
},
"SignatoryCurrentMasterBasic": null,
"SignatoryPastMasterBasic": {
"Signatory": [
{
"SignatoryName": "<name>",
"SignatoryPan": "<pan>",
"SignatoryDesignation": "<designation>",
"SignatoryDateOfAppnt": "<appointment_date>"
},
{
"SignatoryName": "<name>",
"SignatoryPan": "<pan>",
"SignatoryDesignation": "<designation>",
"SignatoryDateOfAppnt": "<appointment_date>"
},
{
"SignatoryName": "<name>",
"SignatoryPan": "<pan>",
"SignatoryDesignation": "<designation>",
"SignatoryDateOfAppnt": "<appointment_date>"
}
]
},
"PotentialRelatedPartyMasterBasic": {
"RelatedParty": [
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
}
]
},
"DirectorAllDirectorshipMasterBasic": {
"Director": [
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": null,
"DirectorDateOfAppnt": null,
"Directorship": [
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
}
]
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": null,
"DirectorDateOfAppnt": null,
"Directorship": [
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
}
]
},
{
"DirectorName": "<name>",
"DirectorDin": "<din>",
"DirectorDesignation": null,
"DirectorDateOfAppnt": null,
"Directorship": [
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
},
{
"CompanyCin": "<cin>",
"CompanyName": "<company_name>",
"CompanyDateOfInc": "<date_of_incorporation>",
"CompanyMcaStatus": "<mca_status>",
"CompanyMcaIndustry": "<industry>",
"CompanyPaidUpCapital": "<paid_up_capital>"
}
]
}
]
}
}
}
}
Success Response Details
The following table outlines the details of the success response from the Fetch Company Details Advanced API:
| Parameter | Type | Description |
|---|---|---|
| status | string | Status of the Fetch Company Details Advanced API response |
| statusCode | integer | The HTTP status code of the response |
| result | object | The main result object containing company details |
| result.CompanyMasterSummary | object | Comprehensive company information and master data |
| result.CompanyMasterSummary.LastUpdatedDateTime | string | The date and time when the company data was last updated |
| result.CompanyMasterSummary.CompanyCin | string | The 21-character Corporate Identification Number of the company |
| result.CompanyMasterSummary.CompanyName | string | The registered name of the company |
| result.CompanyMasterSummary.CompanyDateOfInc | string | The date of incorporation of the company |
| result.CompanyMasterSummary.CompanyRocCity | string | The city where the Registrar of Companies office is located |
| result.CompanyMasterSummary.CompanyRegNumber | string | The registration number assigned to the company |
| result.CompanyMasterSummary.CompanyCategory | string | The category classification of the company |
| result.CompanyMasterSummary.CompanySubCategory | string | The sub-category classification of the company |
| result.CompanyMasterSummary.CompanyClass | string | The class classification of the company |
| result.CompanyMasterSummary.CompanyAuthCapital | string | The authorized capital of the company |
| result.CompanyMasterSummary.CompanyPaidUpCapital | string | The paid-up capital of the company |
| result.CompanyMasterSummary.CompanyFullAddress | string | The complete registered address of the company |
| result.CompanyMasterSummary.CompanyRegState | string | The state where the company is registered |
| result.CompanyMasterSummary.CompanyRegCity | string | The city where the company is registered |
| result.CompanyMasterSummary.CompanyRegPinCode | string | The pin code of the company's registered address |
| result.CompanyMasterSummary.CompanyBookAddress | string | The book address of the company (can be null) |
| result.CompanyMasterSummary.CompanyMcaStatus | string | The current status of the company as per MCA records |
| result.CompanyMasterSummary.CompanyLastAgmDate | string | The date of the last Annual General Meeting |
| result.CompanyMasterSummary.CompanyLastBsDate | string | The date of the last Balance Sheet |
| result.CompanyMasterSummary.CompanyEmail | string | The email address of the company |
| result.CompanyMasterSummary.CompanyWebSite | string | The website URL of the company |
| result.CompanyMasterSummary.CompanyMcaIndustry | string | The industry classification as per MCA |
| result.CompanyMasterSummary.CompanyMcaIndustryDivision | string | The industry division classification as per MCA |
| result.CompanyMasterSummary.CompanyMcaIndustryGroup | string | The industry group classification as per MCA |
| result.CompanyMasterSummary.StatusUnderCIRP | string | The status of the company under Corporate Insolvency Resolution Process (can be null) |
| result.DirectorSignatoryMasterBasic | object | Information about directors and signatories of the company |
| result.DirectorSignatoryMasterBasic.LastUpdatedDateTime | string | The date and time when the director data was last updated |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic | object | Information about current directors of the company |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director | array | Array of current director information |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director[].DirectorName | string | The name of the director |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director[].DirectorDin | string | The Director Identification Number of the director |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director[].DirectorDesignation | string | The designation of the director in the company |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director[].DirectorDateOfAppnt | string | The date of appointment of the director |
| result.DirectorSignatoryMasterBasic.DirectorCurrentMasterBasic.Director[].Directorship | array | Array of other companies where the director holds directorship (can be null) |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic | object | Information about past directors of the company |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director | array | Array of past director information |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director[].DirectorName | string | The name of the past director |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director[].DirectorDin | string | The Director Identification Number of the past director |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director[].DirectorDesignation | string | The designation of the past director in the company |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director[].DirectorDateOfAppnt | string | The date of appointment of the past director |
| result.DirectorSignatoryMasterBasic.DirectorPastMasterBasic.Director[].Directorship | array | Array of other companies where the past director held directorship (can be null) |
| result.DirectorSignatoryMasterBasic.SignatoryCurrentMasterBasic | object | Information about current signatories of the company (can be null) |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic | object | Information about past signatories of the company |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic.Signatory | array | Array of past signatory information |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic.Signatory[].SignatoryName | string | The name of the past signatory |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic.Signatory[].SignatoryPan | string | The PAN number of the past signatory |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic.Signatory[].SignatoryDesignation | string | The designation of the past signatory in the company |
| result.DirectorSignatoryMasterBasic.SignatoryPastMasterBasic.Signatory[].SignatoryDateOfAppnt | string | The date of appointment of the past signatory |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic | object | Information about potential related party companies |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty | array | Array of related party company information |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyCin | string | The CIN of the related party company |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyName | string | The name of the related party company |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyDateOfInc | string | The date of incorporation of the related party company |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyMcaStatus | string | The MCA status of the related party company |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyMcaIndustry | string | The industry classification of the related party company |
| result.DirectorSignatoryMasterBasic.PotentialRelatedPartyMasterBasic.RelatedParty[].CompanyPaidUpCapital | string | The paid-up capital of the related party company |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic | object | Information about all directorships held by directors |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director | array | Array of director information with all their directorships |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].DirectorName | string | The name of the director |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].DirectorDin | string | The Director Identification Number of the director |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].DirectorDesignation | string | The designation of the director (can be null) |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].DirectorDateOfAppnt | string | The date of appointment of the director (can be null) |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship | array | Array of all companies where the director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyCin | string | The CIN of the company where director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyName | string | The name of the company where director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyDateOfInc | string | The date of incorporation of the company where director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyMcaStatus | string | The MCA status of the company where director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyMcaIndustry | string | The industry classification of the company where director holds directorship |
| result.DirectorSignatoryMasterBasic.DirectorAllDirectorshipMasterBasic.Director[].Directorship[].CompanyPaidUpCapital | string | The paid-up capital of the company where director holds directorship |
Error Responses
The following are some error responses from the Fetch Company Details Advanced API:
- No Input Fields
- Empty CIN, No PAN
- Empty PAN, No CIN
- Both CIN and PAN Empty
{
"status": "failure",
"statusCode": 400,
"error": "please enter input field",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "cin should not be empty",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "pan should not be empty",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "both cin and pan should not be empty",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
- Invalid CIN Format
- Empty CIN Only
- Incorrect PAN Only
- Empty CIN with Incorrect PAN
{
"status": "failure",
"statusCode": 400,
"error": "Please enter valid 21-character cin",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "cin should not be empty",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "Please enter valid 10-character company pan",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 400,
"error": "Please enter valid 10-character company pan",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
- Personal PAN
- Missing/Invalid Credentials
- Incorrect CIN Only
- Incorrect CIN with Valid PAN
- Incorrect PAN
{
"status": "failure",
"statusCode": 400,
"error": "Please provide a valid company pan instead of a personal pan",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"message": "Missing/Invalid credentials",
"statusCode": 401,
"status": "failure"
}
{
"status": "failure",
"statusCode": 404,
"error": "The provided cin does not exist in our records",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 404,
"error": "The provided cin does not exist in our records",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
{
"status": "failure",
"statusCode": 404,
"error": "The provided pan does not exist in our records",
"metaData": {
"requestId": "<Request_ID>",
"transactionId": "<Transaction_ID>"
}
}
Error Response Details
A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:
| Status Code | Error Message | Error Description | Error Resolution |
|---|---|---|---|
| 400 | please enter input field | No input fields (CIN or PAN) were provided in the request | Provide at least one of CIN or PAN in the request body |
| 400 | cin should not be empty | The CIN field is empty when no PAN is provided | Provide a valid CIN or provide PAN instead |
| 400 | pan should not be empty | The PAN field is empty when no CIN is provided | Provide a valid PAN or provide CIN instead |
| 400 | both cin and pan should not be empty | Both CIN and PAN fields are empty in the request | Provide at least one of CIN or PAN in the request body |
| 400 | Please enter valid 21-character cin | The provided CIN does not match the required 21-character format | Ensure CIN is exactly 21 characters and matches the required format |
| 400 | Please enter valid 10-character company pan | The provided PAN does not match the required 10-character company PAN format | Ensure PAN is exactly 10 characters and is a valid company PAN format |
| 400 | Please provide a valid company pan instead of a personal pan | A personal PAN was provided instead of a company PAN | Use a company PAN; personal PANs are not accepted by the Fetch Company Details Advanced API |
| 401 | Missing/Invalid credentials | The request is either missing the mandatory appId and appKey combination or has invalid values | Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab |
| 404 | The provided cin does not exist in our records | The provided CIN is not found in the MCA database records | Verify the CIN from MCA records or try with the company PAN |
| 404 | The provided pan does not exist in our records | The provided PAN is not found in the MCA database records | Verify the PAN from MCA records or try with the company CIN |
| 500 | Internal Server Error | There was an error with HyperVerge's server. Please contact the HyperVerge team | Contact the HyperVerge team for resolution |